Web API TypeScript : Obtenir une sécurité de type Fetch pour des applications robustes

Dans le développement web moderne, la récupération de données à partir d'API est une tâche fondamentale. Bien que l'API Fetch native de JavaScript offre un moyen pratique d'effectuer des requêtes réseau, elle manque de sécurité de type inhérente. Cela peut entraîner des erreurs d'exécution et rendre difficile la maintenance d'applications complexes. TypeScript, avec ses capacités de typage statique, offre une solution puissante pour résoudre ce problème. Ce guide complet explore comment implémenter la sécurité de type avec l'API Fetch en TypeScript, créant ainsi des applications web plus robustes et maintenables.

Pourquoi la sécurité de type est importante avec l'API Fetch

Avant de plonger dans les détails de l'implémentation, comprenons pourquoi la sécurité de type est cruciale lorsque vous travaillez avec l'API Fetch :

• Réduction des erreurs d'exécution : Le typage statique de TypeScript permet de détecter les erreurs pendant le développement, évitant ainsi les problèmes d'exécution inattendus causés par des types de données incorrects.
• Amélioration de la maintenabilité du code : Les annotations de type rendent le code plus facile à comprendre et à maintenir, en particulier dans les grands projets avec plusieurs développeurs.
• Expérience développeur améliorée : Les IDE offrent une meilleure autocomplétion, une meilleure mise en évidence des erreurs et des capacités de refactoring lorsque des informations de type sont disponibles.
• Validation des données : La sécurité de type vous permet de valider la structure et les types de données reçus des API, garantissant ainsi l'intégrité des données.

Utilisation de base de l'API Fetch avec TypeScript

Commençons par un exemple de base d'utilisation de l'API Fetch en TypeScript sans sécurité de type :

            async function fetchData(url: string) {
  const response = await fetch(url);
  const data = await response.json();
  return data;
}

fetchData('https://api.example.com/users')
  .then(data => {
    console.log(data.name); // Erreur d'exécution potentielle si 'name' n'existe pas
  });

            

              
                Copy
              
            
          

Dans cet exemple, la fonction `fetchData` récupère les données à partir d'une URL donnée et analyse la réponse en tant que JSON. Cependant, le type de la variable `data` est implicitement `any`, ce qui signifie que TypeScript ne fournira aucune vérification de type. Si la réponse de l'API ne contient pas la propriété `name`, le code lèvera une erreur d'exécution.

Implémentation de la sécurité de type avec les interfaces

La façon la plus courante d'ajouter la sécurité de type aux appels d'API Fetch en TypeScript consiste à définir des interfaces qui représentent la structure des données attendues.

Définition des interfaces

Disons que nous récupérons une liste d'utilisateurs à partir d'une API qui renvoie des données dans le format suivant :

            [
  {
    "id": 1,
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "jane.smith@example.com"
  }
]

            

              
                Copy
              
            
          

Nous pouvons définir une interface pour représenter cette structure de données :

            interface User {
  id: number;
  name: string;
  email: string;
}

            

              
                Copy
              
            
          

Utilisation des interfaces avec l'API Fetch

Maintenant, nous pouvons mettre à jour la fonction `fetchData` pour utiliser l'interface `User` :

            async function fetchData(url: string): Promise {
  const response = await fetch(url);
  const data = await response.json();
  return data as User[];
}

fetchData('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.name); // Accès type-safe à la propriété 'name'
    });
  });

            

              
                Copy
              
            
          

Dans cet exemple mis à jour, nous avons ajouté une annotation de type à la fonction `fetchData`, spécifiant qu'elle renvoie une `Promise` qui se résout en un tableau d'objets `User` (`Promise`). Nous utilisons également une assertion de type (`as User[]`) pour indiquer à TypeScript que les données renvoyées par `response.json()` sont un tableau d'objets `User`. Cela aide TypeScript à comprendre la structure des données et à fournir une vérification de type.

Remarque importante : Bien que le mot-clé `as` effectue une assertion de type, il n'effectue pas de validation d'exécution. Il indique au compilateur ce qu'il faut attendre, mais il ne garantit pas que les données correspondent réellement au type asserté. C'est là que des bibliothèques comme `io-ts` ou `zod` s'avèrent utiles pour la validation d'exécution, comme nous le verrons plus tard.

Tirer parti des generics pour les fonctions Fetch réutilisables

Pour créer des fonctions fetch plus réutilisables, nous pouvons utiliser des generics. Les generics nous permettent de définir une fonction qui peut fonctionner avec différents types de données sans avoir à écrire des fonctions distinctes pour chaque type.

Définition d'une fonction Fetch générique

            async function fetchData(url: string): Promise {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Erreur HTTP ! statut : ${response.status}`);
  }
  const data: T = await response.json();
  return data;
}

            

              
                Copy
              
            
          

Dans cet exemple, nous avons défini une fonction `fetchData` générique qui prend un paramètre de type `T`. La fonction renvoie une `Promise` qui se résout en une valeur de type `T`. Nous avons également ajouté une gestion des erreurs pour vérifier si la réponse a réussi.

Utilisation de la fonction Fetch générique

Maintenant, nous pouvons utiliser la fonction `fetchData` générique avec différentes interfaces :

            interface Post {
  id: number;
  title: string;
  body: string;
  userId: number;
}

fetchData('https://jsonplaceholder.typicode.com/posts/1')
  .then(post => {
    console.log(post.title); // Accès type-safe à la propriété 'title'
  })
  .catch(error => {
      console.error("Erreur lors de la récupération du message :", error);
  });

fetchData('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.email);
    });
  })
  .catch(error => {
      console.error("Erreur lors de la récupération des utilisateurs :", error);
  });

            

              
                Copy
              
            
          

Dans cet exemple, nous utilisons la fonction `fetchData` générique pour récupérer à la fois un seul `Post` et un tableau d'objets `User`. TypeScript déduira automatiquement le type correct en fonction du paramètre de type que nous fournissons.

Gestion des erreurs et des codes d'état

Il est crucial de gérer les erreurs et les codes d'état lorsque vous travaillez avec l'API Fetch. Nous pouvons ajouter une gestion des erreurs à notre fonction `fetchData` pour vérifier les erreurs HTTP et lever une erreur si nécessaire.

            async function fetchData(url: string): Promise {
  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(`Erreur HTTP ! statut : ${response.status}`);
  }
  const data: T = await response.json();
  return data;
}

            

              
                Copy
              
            
          

Dans cet exemple mis à jour, nous vérifions la propriété `response.ok`, qui indique si le code d'état de la réponse se situe dans la plage 200-299. Si la réponse n'est pas OK, nous levons une erreur avec le code d'état.

Validation des données d'exécution avec `io-ts` ou `zod`

Comme mentionné précédemment, les assertions de type TypeScript (`as`) n'effectuent pas de validation d'exécution. Pour garantir que les données reçues de l'API correspondent réellement au type attendu, nous pouvons utiliser des bibliothèques comme `io-ts` ou `zod`.

Utilisation de `io-ts`

`io-ts` est une bibliothèque pour définir des types d'exécution et valider les données par rapport à ces types.

            import * as t from 'io-ts'
import { PathReporter } from 'io-ts/PathReporter'

const UserType = t.type({
  id: t.number,
  name: t.string,
  email: t.string
})

type User = t.TypeOf

async function fetchDataAndValidate(url: string): Promise {
  const response = await fetch(url)
  const data = await response.json()

  const decodedData = t.array(UserType).decode(data)

  if (decodedData._tag === 'Left') {
    const errors = PathReporter.report(decodedData)
    throw new Error(`Erreurs de validation : ${errors.join('\n')}`)
  }

  return decodedData.right
}


fetchDataAndValidate('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.name);
    });
  })
  .catch(error => {
    console.error('Erreur lors de la récupération et de la validation des utilisateurs :', error);
  });

            

              
                Copy
              
            
          

Dans cet exemple, nous définissons un `UserType` à l'aide de `io-ts` qui correspond à notre interface `User`. Nous utilisons ensuite la méthode `decode` pour valider les données reçues de l'API. Si la validation échoue, nous levons une erreur avec les erreurs de validation.

Utilisation de `zod`

`zod` est une autre bibliothèque populaire pour la déclaration et la validation de schémas.

            import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

type User = z.infer;

async function fetchDataAndValidate(url: string): Promise {
  const response = await fetch(url);
  const data = await response.json();

  const parsedData = z.array(UserSchema).safeParse(data);

  if (!parsedData.success) {
    throw new Error(`Erreurs de validation : ${parsedData.error.message}`);
  }

  return parsedData.data;
}


fetchDataAndValidate('https://api.example.com/users')
  .then(users => {
    users.forEach(user => {
      console.log(user.name);
    });
  })
  .catch(error => {
    console.error('Erreur lors de la récupération et de la validation des utilisateurs :', error);
  });

            

              
                Copy
              
            
          

Dans cet exemple, nous définissons un `UserSchema` à l'aide de `zod` qui correspond à notre interface `User`. Nous utilisons ensuite la méthode `safeParse` pour valider les données reçues de l'API. Si la validation échoue, nous levons une erreur avec les erreurs de validation.

`io-ts` et `zod` offrent tous deux un moyen puissant de garantir que les données reçues des API correspondent au type attendu au moment de l'exécution.

Intégration avec des frameworks populaires (React, Angular, Vue.js)

Les appels d'API Fetch de type sûr peuvent être facilement intégrés à des frameworks JavaScript populaires comme React, Angular et Vue.js.

Exemple React

            import React, { useState, useEffect } from 'react';

interface User {
  id: number;
  name: string;
  email: string;
}

function UserList() {
  const [users, setUsers] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    async function fetchUsers() {
      try {
        const response = await fetch('https://api.example.com/users');
        if (!response.ok) {
          throw new Error(`Erreur HTTP ! statut : ${response.status}`);
        }
        const data: User[] = await response.json();
        setUsers(data);
      } catch (error: any) {
        setError(error.message);
      } finally {
        setLoading(false);
      }
    }

    fetchUsers();
  }, []);

  if (loading) {
    return 
Chargement...
;
  }

  if (error) {
    return 
Erreur : {error}
;
  }

  return (
    

      {users.map(user => (
        
{user.name}
      ))}
    
  );
}

export default UserList;

            

              
                Copy
              
            
          

Dans cet exemple React, nous utilisons le hook `useState` pour gérer l'état du tableau `users`. Nous utilisons également le hook `useEffect` pour récupérer les utilisateurs de l'API lorsque le composant est monté. Nous avons ajouté des annotations de type à l'état `users` et à la variable `data` pour garantir la sécurité de type.

Exemple Angular

            import { Component, OnInit } from '@angular/core';
import { HttpClient } from '@angular/common/http';

interface User {
  id: number;
  name: string;
  email: string;
}

@Component({
  selector: 'app-user-list',
  template: `
    

      
{{ user.name }}
    
  `,
  styleUrls: []
})
export class UserListComponent implements OnInit {
  users: User[] = [];

  constructor(private http: HttpClient) { }

  ngOnInit() {
    this.http.get('https://api.example.com/users')
      .subscribe(users => {
        this.users = users;
      });
  }
}

            

              
                Copy
              
            
          

Dans cet exemple Angular, nous utilisons le service `HttpClient` pour effectuer l'appel d'API. Nous spécifions le type de la réponse sous la forme `User[]` à l'aide de generics, ce qui garantit la sécurité de type.

Exemple Vue.js

            



            

              
                Copy
              
            
          

Dans cet exemple Vue.js, nous utilisons la fonction `ref` pour créer un tableau `users` réactif. Nous utilisons le hook de cycle de vie `onMounted` pour récupérer les utilisateurs de l'API lorsque le composant est monté. Nous avons ajouté des annotations de type au ref `users` et à la variable `data` pour garantir la sécurité de type.

Meilleures pratiques pour les appels d'API Fetch de type sûr

Voici quelques bonnes pratiques à suivre lors de l'implémentation d'appels d'API Fetch de type sûr en TypeScript :

• Définir des interfaces : Définissez toujours des interfaces qui représentent la structure des données attendues.
• Utiliser des generics : Utilisez des generics pour créer des fonctions fetch réutilisables qui peuvent fonctionner avec différents types de données.
• Gérer les erreurs : Implémentez une gestion des erreurs pour vérifier les erreurs HTTP et lever des erreurs si nécessaire.
• Valider les données : Utilisez des bibliothèques comme `io-ts` ou `zod` pour valider les données reçues des API au moment de l'exécution.
• Saisir vos états : Lors de l'intégration avec des frameworks comme React, Angular et Vue.js, saisissez vos variables d'état et vos réponses API.
• Centraliser la configuration de l'API : Créez un emplacement central pour l'URL de base de votre API et tous les en-têtes ou paramètres courants. Cela facilite la maintenance et la mise à jour de votre configuration d'API. Pensez à utiliser des variables d'environnement pour différents environnements (développement, mise en scène, production).
• Utiliser une bibliothèque client d'API (facultatif) : Envisagez d'utiliser une bibliothèque client d'API comme Axios ou un client généré à partir d'une spécification OpenAPI/Swagger. Ces bibliothèques offrent souvent des fonctionnalités de sécurité de type intégrées et peuvent simplifier vos interactions API.

Conclusion

L'implémentation de la sécurité de type avec l'API Fetch en TypeScript est essentielle pour créer des applications web robustes et maintenables. En définissant des interfaces, en utilisant des generics, en gérant les erreurs et en validant les données au moment de l'exécution, vous pouvez réduire considérablement les erreurs d'exécution et améliorer l'expérience globale des développeurs. Ce guide fournit un aperçu complet de la manière d'obtenir la sécurité de type avec l'API Fetch, ainsi que des exemples pratiques et des meilleures pratiques. En suivant ces directives, vous pouvez créer des applications web plus fiables et évolutives, plus faciles à comprendre et à maintenir.

Exploration approfondie

• Génération de code OpenAPI/Swagger : Explorez les outils qui génèrent automatiquement des clients API TypeScript à partir de spécifications OpenAPI/Swagger. Cela peut grandement simplifier l'intégration de l'API et garantir la sécurité de type. Les exemples incluent : `openapi-typescript` et `swagger-codegen`.
• GraphQL avec TypeScript : Envisagez d'utiliser GraphQL avec TypeScript. Le schéma fortement typé de GraphQL offre une excellente sécurité de type et élimine la sur-récupération des données.
• Test de la sécurité de type : Écrivez des tests unitaires pour vérifier que vos appels d'API renvoient des données du type attendu. Cela permet de s'assurer que vos mécanismes de sécurité de type fonctionnent correctement.